home *** CD-ROM | disk | FTP | other *** search
/ C/C++ Users Group Library 1996 July / C-C++ Users Group Library July 1996.iso / vol_100 / 129_01 / hack.doc < prev    next >
Text File  |  1985-03-09  |  23KB  |  500 lines
  1. /************************************************************************/
  2. /*                hack.doc                */
  3. /************************************************************************/
  4.  
  5. /************************************************************************/
  6. /*                History                 */
  7. /*                                    */
  8. /* 82Dec07 CrT    Completed.                        */
  9. /* 82Nov23 CrT    Created.                        */
  10. /************************************************************************/
  11.  
  12. /************************************************************************/
  13. /*                Audience                */
  14. /*                                    */
  15. /* Folks trying to read or modify the Citadel code.            */
  16. /************************************************************************/
  17.  
  18. /************************************************************************/
  19. /*                Purpose                 */
  20. /*                                    */
  21. /* Explain the basic data structures and algorithms.            */
  22. /************************************************************************/
  23.  
  24. /************************************************************************/
  25. /*                Overview                */
  26. /************************************************************************/
  27.  
  28.     The fundamental structure of the system is very simple.  CtdlMsg.sys
  29. is a circular file.  New messages are simply written around the buffer
  30. in an endless circle, overwriting old messages in their way.  There is
  31. no other way of deleting messages, and text is never shuffled on disk.
  32. Messages are numbered consecutively and start with an FF (hex)
  33. byte.  Except for this FF start-of-message byte, all bytes in the message
  34. file have the high bit set to 0.  This means that in principle it is
  35. trivial to scan through the message file and locate message N if it
  36. exists, or return error.  (Complexities, as usual, crop up when we
  37. try for efficiency...)
  38.     Each room is basically just a list of message numbers.  Each time
  39. we enter a new message in a room, we slide all the old message-numbers
  40. down a slot, and probably the oldest one falls off the bottom.    Reading
  41. a room is just a matter looking up the messages one by one and printing
  42. them out.  If the message has been overwritten already, we just ignore it.
  43.     Implementing the "new message" function is also trivial in principle:
  44. we just keep track, for each caller in the userlog, of the highest-numbered
  45. message which existed on the >last< call.  (Remember, message numbers are
  46. simply assigned sequentially each time a message is created.  This
  47. sequence is global to the entire system, not local within a room.)  If
  48. we ignore all message-numbers in the room less than this, only new messages
  49. will be printed.  Voila!  Code up the system described thus far, and
  50. you'll have a good approximation to Version 1.    Better stop and reread
  51. everything to here, so you can pick out the fundamental mechanisms among
  52. all of Version 2's bells and whistles.
  53.  
  54. /************************************************************************/
  55. /*        message format on disk    (ctdlMsg.sys)            */
  56. /************************************************************************/
  57.  
  58. Message format has changed relative to V1, in the direction of using
  59. more disk space and providing greater flexibility.
  60.  
  61. A message now consists of a sequence of character strings.  Each string
  62. begins with a type byte indicating the meaning of the string and is
  63. ended with a null.  All strings are printable ASCII: in particular,
  64. all numbers are in ASCII rather than binary.  This is for simplicity,
  65. both in implementing the system and in implementing other code to
  66. work with the system.  For instance, a database driven off Citadel archives
  67. can do wildcard matching without worrying about unpacking binary data such
  68. as dates first.  To provide later downward compatability,
  69. all software should be written to IGNORE fields not currently defined.
  70.  
  71.  
  72. /************************************************************************/
  73. /*          The type bytes currently defined are:         */
  74. /************************************************************************/
  75.  
  76. BYTE    Mnemonic    Comments
  77.  
  78. 0xFF            Start-of-message indicator.  Followed by local
  79.             message ID# as ASCII string, null-terminated as
  80.             always.  This byte is the >only< byte which has
  81.             the high bit set in a Citadel message.buf file.
  82.             This field must be present in every message.
  83. A    Author        Name of originator of message.
  84. D    Date        Date message was created.
  85. M    Message     Text of message.  Is last field in a message, by
  86.             definition.  Following data will be ignored.
  87.             This field must be present in every message.
  88. N    Name        Human name for node originated on.  Used on
  89.             title line of foreign messages.  Ex:
  90.             ODD-DATA
  91.             will produce a title message something like
  92.             82Nov23 from Cynbe ru Taren @ODD-DATA
  93. O    Origin        ID of node message originated on: Country code plus
  94.             phone number of system.  (Not stored for locally
  95.             originated messages.)  Ex:
  96.             US 206 633 3282
  97. R    Room        Room of origin.  Topic.
  98. S    Source ID#    Message ID # on system message was created on.
  99.             Two 16-bit integers (high and low halves of
  100.             full 32-bit ID#) separated by a blank.    Ex:
  101.             0 13654
  102. T    To        Addressee.  Used only for private messages in Mail>,
  103.             in version 2.00 .
  104.             EXAMPLE
  105.  
  106. Let <FF> be a 0xFF byte, and <0> be a null (0x00) byte.  Then a message
  107. which prints as
  108.  
  109. LOGLAN> read new
  110.  
  111. 82Nov04 From James Cooke Brown
  112. Loi uiue i Ti logla
  113.  
  114. LOGLAN>
  115.  
  116. might be stored as
  117.  
  118. <FF>0 3583<0>D82Nov04<0>AJames Cooke Brown<0>RLOGLAN<0>MLoi uiue i Ti logla<0>
  119. |--Local ID--|---Date---|-----Author---------|--Room---|-------Message--------|
  120.  
  121. The date, room and author fields could be in any order. Not all fields
  122. are printed by default.  The local ID# and Room field are suppressed here.
  123. An isolated system will not normally have use for fields beyond those
  124. used in this example.
  125.  
  126. Lines are marked with C NewLine (ASCII LF) characters, within the message
  127. text proper.
  128.  
  129. /************************************************************************/
  130. /*                Networking                    */
  131. /************************************************************************/
  132.  
  133. Citadel nodes network by sharing one or more rooms.  Any Citadel node
  134. can choose to keep an image of any public room on any other Citadel node
  135. (subject to willingness to foot the phone bills, of course!).  The
  136. procedure in essence simply involves calling the imaged node up periodically
  137. and copying any new messages in the imaged room into the local image.
  138.  
  139. There is no necessary reciprocity or pre-arrangement, although convenience
  140. and politeness respectively suggest both.  The node which gets the
  141. information foots the phone bill for the transaction.  This promotes
  142. simple and harmonious relations between the nodes.
  143.  
  144. Complexities arise primarily from the possibility of densely connected
  145. networks: one does not wish to accumulate multiple copies of a given
  146. message, which can easily happen.  Nor does one want to see old messages
  147. percolating indefinitely through the system.
  148.  
  149. This problem is handled by a simple brute-force mechanism: each node
  150. keeps a list of all messages it has seen recently, recording origin
  151. system, creation date, and original ID#.  When downloading, messages
  152. which have already been seen, or which are too old to be remembered,
  153. are skipped.  Messages can percolate outward through a large network
  154. with no global routing or control, but do not reproduce wildly or
  155. cycle indefinitely.
  156.  
  157.  
  158. The above discussion should make the function of the new
  159. fields reasonably clear:
  160.  
  161.  o  Every message needs a local ID#, so the system can determine if
  162.     a given caller has seen it before.
  163.  o  Travelling messages need to carry system of origin, date of
  164.     origin, and original ID# with them, to keep reproduction and
  165.     cycling under control.
  166.  
  167.  
  168. (Uncoincidentally) the format used to transmit messages for networking
  169. purposes is precisely that used on disk, except that lines are marked
  170. with ASCII CR characters in stead of ASCII LF characters.  The current
  171. distribution does not include active network support code;  these comments
  172. are included in the hope of discouraging people from modifying the disk
  173. format, date field or whatever in ways which will make their local no